Fixes: DRIVER-540

4.x port of #867 (which targeted scylla-3.x).

Supersedes #874 (closed — AI had committed directly onto scylla-4.x instead of a feature branch).

Problem

When a DriverTimeoutException fires, the existing log output gives no information about why it happened. There are two distinct failure modes that look identical:

1. Pool contention — requests queue inside the driver waiting to acquire a stream ID; the cumulative wait pushes elapsed time past the configured timeout. The request may never have reached the server.
2. Server-side slowness — requests were sent but the server took too long to respond (e.g. reader_concurrency_semaphore stall). The driver gave up, but the server may still be processing them, orphaning stream IDs.

Without knowing which nodes had in-flight requests and what the pool state looked like at timeout time, diagnosing which scenario occurred requires guesswork.

Changes

DriverTimeoutException (public API)

A new NodeDiagnostics public inner class is added with fields captured at timeout time:

Pool fields are set to UNAVAILABLE (-1) when the pool was removed between dispatch and timeout.

A new constructor DriverTimeoutException(String baseMessage, List<NodeDiagnostics>) generates the full message internally (per reviewer request). The existing single-arg constructor is unchanged.

getNodeDiagnostics() allows callers to inspect fields programmatically, consistent with the 3.x OperationTimedOutException approach.

Message format

Query timed out after PT0.5S — nodes in flight: /10.0.0.1:9042 [channel in-flight: 5, pool in-flight: 12, pool available ids: 988, pool orphaned ids: 2], /10.0.0.2:9042 [channel in-flight: 3, pool in-flight: 8, pool available ids: 992, pool orphaned ids: 0]

Diagnosing failure modes:

• poolAvailableIds near zero → pool contention; requests queuing inside the driver before reaching the server
• poolAvailableIds normal + high channelInFlight → server is slow; requests sent but not answered within the timeout
• High poolOrphanedIds → previous timeouts consumed stream IDs that the driver is still waiting to reclaim

Handler files

Each handler builds a List<NodeDiagnostics> at the moment the timer fires and passes it to the new constructor:

• CqlRequestHandler.java — iterates inFlightCallbacks (multi-node list)
• GraphRequestHandler.java — same pattern
• CqlPrepareHandler.java — single-element list from initialCallback
• ContinuousRequestHandlerBase.java — scheduleGlobalTimeout (multi-node list) + onPageTimeout (single-element list)

The per-handler buildTimeoutMessage() / buildGlobalTimeoutMessage() helpers are removed; message generation now lives in DriverTimeoutException.buildMessage().

Architecture differences from 3.x

In 3.x, the timeout is per-node (SpeculativeExecution.onTimeout()). In 4.x, a single timer covers the entire request, but multiple nodes can be in-flight simultaneously (speculative executions + retries).

Notes

• No logic changes; diagnostics only.
• All accessed state is safe from the Netty timer thread: inFlightCallbacks is a CopyOnWriteArrayList, session.getPools() returns a ConcurrentHashMap, and pool/channel stats use atomic operations.
• Pool lookup is null-checked defensively (host may be removed between dispatch and timeout).
• All existing test assertions use substring matching and pass unchanged (411 unit tests green).